---
title: Adding New Utilities
description: Extending Tailwind with your own custom utility classes.
---

import { TipGood, TipBad } from '@/components/Tip'

Although Tailwind provides a pretty comprehensive set of utility classes out of the box, you may run into situations where you need to add a few of your own.

Deciding on the best way to extend a framework can be paralyzing, so here are some best practices to help you add your own utilities in the most idiomatic way possible.

---

## Using CSS

The easiest way to add your own utilities to Tailwind is to simply add them to your CSS.

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  .scroll-snap-none {
    scroll-snap-type: none;
  }
  .scroll-snap-x {
    scroll-snap-type: x;
  }
  .scroll-snap-y {
    scroll-snap-type: y;
  }
}
```

By using the `@layer` directive, Tailwind will automatically move those styles to the same place as `@tailwind utilities` to avoid unintended specificity issues.

Using the `@layer` directive will also instruct Tailwind to consider those styles for purging when purging the `utilities` layer. Read our [documentation on optimizing for production](/docs/optimizing-for-production) for more details.

### Generating responsive variants

If you'd like to generate [responsive variants](/docs/responsive-design) of your own utilities based on the breakpoints defined in your `tailwind.config.js` file, wrap your utilities in the `@variants` directive and add `responsive` to the list of variants:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  @variants responsive {
    .scroll-snap-none {
      scroll-snap-type: none;
    }
    .scroll-snap-x {
      scroll-snap-type: x;
    }
    .scroll-snap-y {
      scroll-snap-type: y;
    }
  }
}
```

Tailwind will automatically generate prefixed versions of each custom utility that you can use to conditionally apply those styles at different breakpoints:

```html
<!-- Use `scroll-snap-type: none` by default, then use `scroll-snap-type: x` on medium screens and up -->
<div class="scroll-snap-none **md:scroll-snap-x**"></div>
```

Learn more about responsive utilities in the [responsive design documentation](/docs/responsive-design).

### Generating dark mode variants

If you'd like to generate [dark mode variants](/docs/dark-mode) of your own utilities, first make sure `darkMode` is set to either `media` or `class` in your `tailwind.config.js` file:

```js
// tailwind.config.js
module.exports = {
  darkMode: 'media'
  // ...
}
```

Next, wrap your utilities in the `@variants` directive and add `dark` to the list of variants:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  @variants dark {
    .filter-none {
      filter: none;
    }
    .filter-grayscale {
      filter: grayscale(100%);
    }
  }
}
```

Tailwind will automatically generate prefixed versions of each custom utility that you can use to conditionally apply those styles at different states:

```html
<div class="filter-grayscale **dark:filter-none**"></div>
```

Learn more about dark mode utilities in the [dark mode documentation](/docs/dark-mode).

### Generating state variants

If you'd like to create [state variants](/docs/hover-focus-and-other-states) for your own utilities, wrap your utilities in the `@variants` directive and list the variants you'd like to enable:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  @variants hover, focus {
    .filter-none {
      filter: none;
    }
    .filter-grayscale {
      filter: grayscale(100%);
    }
  }
}
```

Tailwind will automatically generate prefixed versions of each custom utility that you can use to conditionally apply those styles at different states:

```html
<div class="filter-grayscale **hover:filter-none**"></div>
```

State variants are generated in the same order you list them in the `@variants` directive, so if you'd like one variant to take precedence over another, make sure you list that one last:

```css
/* Focus will take precedence over hover */
@variants hover, focus {
  .filter-grayscale {
    filter: grayscale(100%);
  }
  /* ... */
}

/* Hover will take precedence over focus */
@variants focus, hover {
  .filter-grayscale {
    filter: grayscale(100%);
  }
  /* ... */
}
```

Learn more about state variants in the [state variants documentation](/docs/hover-focus-and-other-states).

---

## Using a plugin

In addition to adding new utility classes directly in your CSS files, you can also add utilities to Tailwind by writing your own plugin:

```js
// tailwind.config.js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      const newUtilities = {
        '.filter-none': {
          filter: 'none',
        },
        '.filter-grayscale': {
          filter: 'grayscale(100%)',
        },
      }

      addUtilities(newUtilities, ['responsive', 'hover'])
    })
  ]
}

```

This can be a good choice if you want to publish your custom utilities as a library or make it easier to share them across multiple projects.

Learn more in the [utility plugin documentation](/docs/plugins#adding-utilities).
